<HTML><HEAD><TITLE>copy_term(?OldTerm, -NewTerm)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Term Manipulation</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>copy_term(?OldTerm, -NewTerm)</H1>
A copy of OldTerm with new variables is created and unified with NewTerm.


<DL>
<DT><EM>OldTerm</EM></DT>
<DD>Prolog term.
</DD>
<DT><EM>NewTerm</EM></DT>
<DD>Prolog term.
</DD>
</DL>
<H2>Description</H2>
   A copy of OldTerm is created, ie.  a term that is similar to OldTerm but
   the free variables of OldTerm have been replaced by new variables which
   do not occur elsewhere.  In other words, the new term is a most general
   variant of the old one, in the sense of variant/2.

<P>
   Attributed variables are treated like normal variables, except that their
   attributes are copied as specified by the corresponding copy_term handler.
   This would usually imply that properties of the variable which can be
   interpreted as unary constraints (such as its domain) are copied, while
   attributes that link the variable to other variables or objects are ignored.

<P>
   If the term to be copied contains ground subterms (subterms without
   variables), then these subterms are shared between the original and
   the copy.  This optimization is only visible when using the nonlogical
   setarg/3 primitive on such a subterm - the safest way to enforce
   copying in such circumstances is to add a dummy variable argument.

<P>
   Note that when the structure of the term to be copied is known, then
   it is more efficient to use specialised unification code or a combination
   of functor/3 and arg/3 to do the job.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>copy_term(?, -) is det
</UL>
<H2>Examples</H2>
<PRE>
   Success:
   copy_term(a, C).          (gives C=a).
   copy_term(s(X,a,Y,X), C). (gives C=s(_1, a, _2, _1)).
   copy_term([X,2|Y], C).    (gives C=[_1, 2| _2]).
   copy_term(X, C).
   copy_term(X, s(1,2,3)).

   X::5..8, copy_term(f(X), C).	(gives C=f(_1{5..8})).

   Fail:
   copy_term(s(X,X), s(3,4)).
</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/termmanip/copy_term_vars-3.html">copy_term_vars / 3</A>, <A HREF="../../kernel/termmanip/copy_term-3.html">copy_term / 3</A>, <A HREF="../../kernel/termcomp/variant-2.html">variant / 2</A>, <A HREF="../../kernel/termmanip/functor-3.html">functor / 3</A>, <A HREF="../../kernel/termmanip/term_variables-2.html">term_variables / 2</A>
</BODY></HTML>
